Undocumented APIs pose significant challenges in software development for several reasons:
- Lack of Clarity: developers struggling to understand how to use the API correctly. This can lead to misuse and unexpected
results.
- Increased Development Time: developers spending extra time reading and understanding the source code, which slows down the
development process.
- Error Prone: developers are more likely to make mistakes that lead to bugs or system crashes when the intent or the error
handling of an API is not clear.
- Difficult Maintenance and Updates: developers may not understand the existing functionality well enough to add new features
without breaking the existing ones.
- Poor Collaboration: collaboration, when there is lack of documentation, leads to confusion and inconsistencies.
It is recommended to document the API using ASDoc to clarify what is the contract of the API. This is especially important for
public APIs, as they are used by other developers.
Exceptions
Classes or class elements with an ASDoc @private comment are ignored by this rule.
/**
* @private // This class and all its elements are ignored
*/
public class MyClass { // Compliant
public var myLabel:String; // Compliant
}
public class AnotherClass { // Noncompliant; class not @private and not documented
/**
* @private
*/
public var name:String; // Compliant
}
